RecsForPlacementContext

IMPORTANT: This API is currently limited to specific customers. Please contact your Algonomy team if you want to use this API.

Description

This API provides a mechanism to make a single request for multiple placements, while passing different contexts for each placement. You can also force a specific strategy to play or apply attribute, category, or price filters to the resulting recommendations.

This allows you to have multiple placements on a single page, where each placement is seeded by a different category. The API accepts all the same parameters as the recsForPlacements API, and the contextual information is sent in the body of the Post request.

The difference between recsForPlacements and recsForPlacementsContext API:

recsForPlacements	recsForplacementsContext
GET api call	POST api call
Accepts query parameters documented	Accepts query parameters document in recsForPlacements + a POST body (placement context)

Payload

Name	Required or Optional	Description
attributeConfigs	Optional	A list of different attribute name and value which the recommended products should satisfy. Example: [{"attributeName": "color", "attributeValues": ["blue", "red"]}]
attributeInfo	Optional	Holds the information about the different attributes and how they should be applied.
categorySeed	Optional	The seed category to be used by the placement.
enablePartialAttributeMatching	Optional	True/false. The default is false; provides only full matching results in the response. When set to true, allows the response to include products that partially match attribute filters applied in the request. Products are ranked based on the count of matched attributes. If filtering on multiple attributes, the API prioritizes products matching all filters first. If the placement is not filled with exact matches, partially matching products are returned. Example: enablePartialAttributeMatching = true Note: Enable the "enable partial attribute matching" option in the Site Configuration.
enableStrategyDuplication	Optional	Default value is false. When set true, allows a strategy to be played multiple times on a particular page for the different placements. Example: enableStrategyDuplication = true
filterAtr	Optional	Passes attribute and value, list is or'd
filterConfig	Optional	Filters to be applied to the items in the response for the given placement. minPriceFilter: region price, sale price or if no sale price then list price maxPriceFilter: region price, sale price or if no sale price then list price categoryFilter: products that have one or more categories Example: {minPriceFilter: null, maxPriceFilter: 100}
includeProductsMatchingFilters	Optional	True or False; Default value is true. Example: includeProductsMatchingFilters = true Applied for attributeConfigs, categoryFilter, minPriceFilter, maxPriceFilter true means it is an inclusive filter i.e. only recommend products that match the filter. Example: Only return products that belong to category 487553. false means do not recommend products that match the filter. Example: Do not return products that belong to category 487553.
placementConfig	Optional	Object which can hold different (overriding) configurations for this placement. (Currently, only supports 'strategyConfig')
placementContextInfo	Required	A list which holds information for each placement such as placement name, strategies to be run for that placement, category seed, different filters etc.
placementName	Required	Name of the placement as specified in the request. Example: category_page
productIds	Optional	List of productIds which is utilized by the product seeded strategies such as ClickCP. Example: ["12345", "67890"]
productsMatchAllAttributes	Optional	Default value is true. When set to true, keeps only those products which have all the attributes as mentioned in the attributeConfigs. If not set, keeps only those products which have at least one attribute of attributeConfigs. Example: productsMatchAllAttributes = true
reorder	Optional	Default value is false. If the client specifies reorder to be true, it means the client wants our machine learning algorithms (XO) to run and reorder the strategies list provided. If the default value for the 'recsForPlacementContext' API is false, the client must provide strategies in the proper order.
strategyConfig	Optional	Object which consists of overriding strategy configurations. Example: {"strategies": ["BestSellers", "TopRated"]}
strategies	Optional	A list of strategies which will be forced run. These strategies will run first before any Experience Optimizer (XO) selected strategy or strategy rules preferred strategies. The client can pass a backfilled strategy in the list. If none of the strategies specified in the list returns or satisfies recommendations after filtering, the call will fallback to strategies preferred in strategy rules targeting the given placement and then XO selected strategies from the strategies enabled for the given page type. Fall back order: Request strategies defined (strategies listed within the API call) Strategies preferred within strategy rules targeting the given placement Experience Optimizer selected strategies based on those that are enabled for the page type in question Example: ["CategoryTopSellers", "CategoryTopProducts"]

IMPORTANT: For pages that have a seed, you need to include the seed attribute in the placementConfig object. For example, if you are on an Item or Cart page, you need to send the productIds attribute; if you send a request to a Category page, you need to send the categorySeed attribute;

Exceptions

Exception	Condition
ArgumentNullException	message is null.

Examples

Example 1

Example Request:

Copy

http://recs.richrelevance.com/rrserver/apiclick?a=5c84741760900058&vg=c12ab4b2...s=1437007681319&pg=1653&p=36714988&ind=0

Payload:

Copy

{   
    "placementContextInfo" : [
        {
        "placementName" :"item_page.recsmiddle",
        "placementConfig" : {
            "strategyConfig": {
                "strategies" : ["ViewedPurchased","ClickEV", "CategoryTopSellers"],
                "reorder" : false
            },
            "categorySeed" : "electronics",
            "filterConfig" : {
                "includeProductsMatchingFilters" : false,
                "categoryFilters" : ["video"],
                "minPriceFilter": null,
                "maxPriceFilter" : 5000,
                "attributeInfo" : {
                    "productsMatchAllAttributes" : false,
                    "attributeConfigs" : [
                        {
                            "attributeName" : "prime",
                            "attributeValues" : ["false"]
                        },
                        {
                            "attributeName" : "Clearance",
                            "attributeValues" : ["N"]
                        }
                    ]
                }
            },
            "productIds" : ["15847591"]
         }
       }
    ],
    "enableStrategyDuplication" : false
}

In the above example, the client can send multiple placement objects.

Note: Placement name passed in the request must be same as placementName mentioned in the post body.

Here, the request is sent for 2 placements :

item_page.recsmiddle
item_page.rr1.

But in the post body, only 'recsmiddle' is defined. So, for 'recsmiddle' placement, the strategies mentioned will be forced to run, but for 'item_page.rr1', the default pipeline will work (no force strategy, since no overriding context was passed).

Example Response:

Copy

{
  "rcs": "eF5j4cotK8lM4TMzsNA11DVkKU32MEkyBAJjM11jYzMzXRNTozRdA0sgYZxiammQaGJmZmaaDABuTQ0O",
  "placements": [
    {
      "htmlElementId": "home_page_0",
      "placementType": "home_page",
      "strategyMessage": "Shop Top Sellers",
      "html": "",
      "placement": "home_page.rr1",
      "recommendedProducts": [
        {
          "clickURL": "https://integration.richrelevance.com/rrserver/apiclick?a=showcaseparent&cak=776cdd80331919e7&ct=http%3A%2F%2Flabs.richrelevance.com%2Fstorre%2Fcatalog%2Fproduct%2Fview%2Fsku%2F22127002&vg=4b121136-3366-452f-092f-3d590a46665c&stid=126&pti=9&pa=11339&pos=0&p=22127002&channelId=776cdd80331919e7&s=827ccb0eea8a706c4c34a16891f84e7b&u=12345&mvtId=-1&mvtTs=1529712166361",
          "regionPriceDescription": "",
          "salePriceRangeCents": [
            1,
            1
          ],
          "rating": 3.884,
          "numReviews": 0,
          "priceRangeCents": [
            1,
            1
          ],
          "categoryIds": [
            "Electronics",
            "Electronics.Computers",
            "Electronics.Computers.Tablet PCs"
          ],
          "clickTrackingURL": "https://integration.richrelevance.com/rrserver/apiclick?a=showcaseparent&cak=776cdd80331919e7&vg=4b121136-3366-452f-092f-3d590a46665c&stid=126&pti=9&pa=11339&pos=0&p=22127002&channelId=776cdd80331919e7&s=827ccb0eea8a706c4c34a16891f84e7b&u=12345&mvtId=-1&mvtTs=1529712166361",
          "salePriceCents": 1,
          "regionalProductSku": "22127002",
          "imageURL": "http://labs.richrelevance.com/storre/media/catalog/product/n/e/nextbook-7quot-tablet-with-8gb-memory-with-google-mobile-services-73fbdb1640b18e99695aa87c7da712f5.jpg",
          "name": "\"Nextbook 7\\\" Tablet with 8GB Memory with Google Mobile Services\"",
          "genre": "default",
          "isRecommendable": true,
          "priceCents": 6900,
          "attributes": {
            "MktplcInd": [
              "W"
            ],
            "Clearance": [
              "N"
            ],
            "97CentShipping": [
              "N"
            ],
            "Rollback": [
              "N"
            ],
            "Online": [
              "Y"
            ],
            "ListPrice": [
              "79"
            ],
            "AddToCart": [
              "Y"
            ],
            "IsReducedPrice": [
              "N"
            ],
            "IsSubmap": [
              "N"
            ],
            "S2S": [
              "Y"
            ]
          },
          "id": "22127002",
          "categories": [
            {
              "hasChildren": false,
              "name": "Electronics",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics",
              "isActive": false
            },
            {
              "hasChildren": false,
              "name": "Computers",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics.Computers",
              "isActive": false
            },
            {
              "hasChildren": false,
              "name": "Tablet PCs",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics.Computers.Tablet PCs",
              "isActive": false
            }
          ],
          "productURL": "http://labs.richrelevance.com/storre/catalog/product/view/sku/22127002",
          "brand": "Nextbook"
        }
      ]
    }
  ],
  "viewGuid": "4b121136-3366-452f-092f-3d590a46665c",
  "status": "ok"
}

Example 2

Example Request:

Copy

http://localhost:8101/rrserver/api/rrPlatform/recsForPlacementsContext?apiClientKey=0503a7f4357b2f36&apiKey=45a98cdf34a56c26&placements=category_page.recsbottom&sessionId=7FzEGpX7iqeNZnWw9hNR6Jegy1kVCh11&rcs=eF4FwbERgCAQBMCEyF7O8eDgoQPb4EFnDMzU-t0Ny_0911yzIphF1labpY0oCWB4xy6fpk7BhxvUzwOmRPSS64gclJcfbskRrQ&l=1&pref=
https://www.build.com/bathroom/c108412&c=976

Payload:

Copy

[
    {
    "placementName" :"category_page.recsbottom",
    "placementConfig" : {
        "strategyConfig": {
            "strategies" : [ "CategoryTopProducts","CategoryTopSellers"]
        },
        "categorySeed" : "889",
        "filterConfig" : {
            "includeProductsMatchingFilters" : true,
            "categoryFilters" : ["889-506438", "508606-516708-508608"],
            "minPriceFilter": null,
            "maxPriceFilter" : 2000,
            "attributeConfigs" : [
                    {
                        "attributeName" : "gender",
                        "attributeValues" : ["female"]
                    },
                    {
                        "attributeName" : "is_savings_constant",
                        "attributeValues" : ["true"]
                    }
                ]
        }
     }
   }
]

Example 3

In the response, the 'enablePartialAttributeMatching' is set to true, indicating that partial attribute matching is enabled. This allows the API to return products that partially match the attribute filters specified in the request body.

Example Request:

Copy

https://recs.richrelevance.com/rrserver/api/rrPlatform/recsForPlacementsContext?placements=category_page.guided_selling&includeStrategyData=true&excludeItemAttributes=false&excludeHtml=true&categoryData=false&apiClientKey=e720fcd382666696&apiKey=d8baf6848041b078&sessionId=hfws11wljsln&rid=027&excludeItemAttributes=true&rcs=eF4NxbERgCAMBdCGyl3-XRICIRu4BgG5s7BT59fXvLRd731OYtcMtn-xyqUWgTPA6Rn7EdbYV0f4FCiNgK-2oFIiWyZi7R9_cRG9

Payload:

Copy

{
  "placementContextInfo": [
    {
      "placementName": "category_page.guided_selling",
      "placementConfig": {
        "strategyConfig": {
          "strategies": ["Category - Top Selling"],
          "reorder": false
        },
        "categorySeed": "mens-fleece-sweaters",
        "filterConfig": {
          "includeProductsMatchingFilters": true,
          "enablePartialAttributeMatching": true,
          "categoryFilters": [],
          "minPriceFilter": null,
          "maxPriceFilter": null,
          "attributeInfo": {
            "productsMatchAllAttributes": true,
            "attributeConfigs": [
              {
                "attributeName": "gender",
                "attributeValues": ["Men's"]
              },
              {
                "attributeName": "size",
                "attributeValues": ["S","M"]
              },
              {
                "attributeName": "color-family",
                "attributeValues": ["black"]
              },
              {
                "attributeName": "best-use",
                "attributeValues": ["Multisport", "Fitness"]
              }
            ]
          }
        },
        "productIds": []
      }
    }
  ],
  "enableStrategyDuplication": false
}

Considerations

Advanced Merchandising rules always run first before any strategy (customer defined or out-of-the box strategy) in the Algonomy system. If Advanced Merchandising rules are targeting a placement and the placement is specified in the request, and the rules fulfill the placement requirements, then Advanced merchandising recommendations will be returned, ignoring this context passed. The client needs to make sure no Advanced Merchandising rules are targeting the same placement.